IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/share/catman/p_man/cat3/intro.z/intro

Text File | 1998-10-20 | 24KB | 388 lines

iiiinnnnttttrrrroooo((((3333))))                                                              iiiinnnnttttrrrroooo((((3333))))



NNNNAAAAMMMMEEEE
     intro - introduction to functions and libraries

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     This section describes functions found in various libraries, other than
     those functions that directly invoke IRIX system primitives, which are
     described in Section 2 of this volume.  Function declarations can be
     obtained from the _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee files indicated on each page.  Certain major
     collections are identified by a letter after the section number.

     In general, routines in these libraries are not MP or MT (multi-threaded)
     safe, and therefore must be explictly protected by one of the
     synchronization primitives in the users code.  Exceptions are noted in
     the man pages.  See section 3333PPPP below.

     (3C)  These functions, together with those of Section 2 and those marked
           (3S), constitute the standard C library, _llll_iiii_bbbb_cccc, which is
           automatically linked by the C compilation system.  The standard C
           library is implemented as a shared object, _llll_iiii_bbbb_cccc_...._ssss_oooo_...._1111.

     (3G)  These functions constitute the IRIS Graphics Library which are
           documented in the _G_r_a_p_h_i_c_s _L_i_b_r_a_r_y _U_s_e_r'_s _G_u_i_d_e.  The ----llllggggllll and ----llllmmmm
           flags should be specified to access the graphics library.
           Declarations for these functions may be obtained from the include
           file <_g_l._h>.  <_d_e_v_i_c_e._h> and <_g_e_t._h> define other constants used by
           the Graphics Library.

     (3M)  These functions constitute the Math Library, _l_i_b_m.  Use the ----llllmmmm
           option to _c_c(1) or _l_d(1) to have the link editor search this
           library.  Declarations for these functions may be obtained from the
           include file <_m_a_t_h._h>.

     (3S)  These functions constitute the ``standard I/O package'' (see
           _s_t_d_i_o(3S)).  These functions are in the standard C library _l_i_b_c,
           already mentioned.  Declarations for these functions may be
           obtained from the include file <_s_t_d_i_o._h>.

     (3G)  These functions constitute the general-purpose library, _llll_iiii_bbbb_gggg_eeee_nnnn.
           This library is implemented as a shared object and an archive, and
           is not automatically linked by the C compilation system.  Specify
           _----_llll_gggg_eeee_nnnn on the _cccc_cccc command line to link with this library.
           Declarations for these functions may be obtained from the include
           file <_l_i_b_g_e_n._h>.

     (3B)  IRIX supports many 4.3BSD system calls and library routines.  To
           get the maximum Berkeley compatibility, use the following compile
           line:

                cc -D_BSD_COMPAT -o prog prog.c -lbsd

           ----DDDD____BBBBSSSSDDDD____SSSSIIIIGGGGNNNNAAAALLLLSSSS on the compile line specifically selects the
           Berkeley signal routines and ----DDDD____BBBBSSSSDDDD____TTTTIIIIMMMMEEEE selects the Berkeley



                                                                        PPPPaaaaggggeeee 1111






iiiinnnnttttrrrroooo((((3333))))                                                              iiiinnnnttttrrrroooo((((3333))))



           time-of-day routines. Both are a subset of the compatibility
           specified by ----DDDD____BBBBSSSSDDDD____CCCCOOOOMMMMPPPPAAAATTTT.
           The following 4.3BSD standard C Library routines in _l_i_b_b_s_d have
           different arguments or conflicting semantics with the routines in
           IRIX _l_i_b_c having the same names:  _d_u_p_2, _g_e_t_g_r_o_u_p_s, _g_e_t_p_g_r_p,
           _s_e_t_g_r_o_u_p_s, _s_e_t_p_g_r_p.  To compile and link a program that calls the
           BSD version of any of these routines, use a command of the form:

                cc  prog.c -lbsd

           See the "BSD Compatibility" section below for more details.

     (3N)  There are actually 3 types of networking in IRIX.

           1)  BSD sockets implemented in the kernel, along with SUN RPC and
           NIS (YP).  The functions that implement these calls are in libc
           [see (_3_C) section above].

           2)  SVR4-style STREAMS/TLI networking (not sockets), along with
           SVR4-style RPC.  SVR4-style RPC doesn't work with sockets, only
           with the TLI.  Also, SVR4-style networking does not support NIS
           [see _i_n_t_r_o(3N)].  The functions that implement these calls are in
           libnsl, and to use them, the code must be compiled with :

                cc -D_SVR4_TIRPC  prog.c -lnsl


           3)  SVR4 emulation of sockets.  This is an implementation of
           sockets entirely in a library (libsocket) that sits on top of
           libnsl.  There are no header file differences for libsocket.  The
           MIPS ABI-compliant programs that use sockets must (in order to be
           ABI-compliant) link with libsocket.  There is no NIS support for
           programs linked with libsocket [see _i_n_t_r_o(3N)].  To compile such a
           program, use:

                cc prog.c -lsocket


     (3Y) Remote Procedure Call (RPC) and NIS support routines.  These
          functions are in the standard C library _l_i_b_c, already mentioned.

     (3R) Remote Procedure Call services built on top of the Sun RPC protocol.
          To compile and link a program that calls any of these routines, use
          a command of the form:

               cc prog.c -lrpcsvc


     (3P) These functions constitute the parallel processing interfaces.  They
          comprise standard C library thread safe functions and POSIX threads
          interfaces.  IRIX supports two threading models:  _s_p_r_o_c(2), process
          level threads (IRIX, proprietary) and _p_t_h_r_e_a_d_s(3P) (POSIX threads).



                                                                        PPPPaaaaggggeeee 2222






iiiinnnnttttrrrroooo((((3333))))                                                              iiiinnnnttttrrrroooo((((3333))))



          The models are quite different and cannot interact in the same
          program; an sproc program cannot create pthreads and vice-versa.
          Thread safe interfaces may be accessed by multiple threads or
          processes simultaneously and are guaranteed to behave correctly.

          In the sproc model no locking or single threading is done until the
          program makes the first call to _s_p_r_o_c().  The _u_s_c_o_n_f_i_g(3P) interface
          can be used to alter the thread safe behavior of these routines.
          Sproc programs wishing to do parallel processing should define the
          feature test macros ____SSSSGGGGIIII____MMMMPPPP____SSSSOOOOUUUURRRRCCCCEEEE and ____SSSSGGGGIIII____RRRREEEEEEEENNNNTTTTRRRRAAAANNNNTTTT____FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS.

          ____SSSSGGGGIIII____MMMMPPPP____SSSSOOOOUUUURRRRCCCCEEEE changes the _e_r_r_n_o variable from a global to a per
          thread private variable.  It also makes certain macros and function
          prototypes visible.

          Pthread programs should enable the thread safe options including
          reentrant functions and per thread _e_r_r_n_o by setting the POSIX
          feature test macro, ____PPPPOOOOSSSSIIIIXXXX____CCCC____SSSSOOOOUUUURRRRCCCCEEEE to the value _1_9_9_5_0_6_L or greater;
          the file <_p_t_h_r_e_a_d._h> enables these options automatically.

          The following calls have been single threaded so that multiple
          shared processes accessing them simultaneously will function
          correctly:  _g_e_t_c, _p_u_t_c, _f_g_e_t_c, _f_p_u_t_c, _u_n_g_e_t_c, _g_e_t_w, _p_u_t_w, _g_e_t_s,
          _f_g_e_t_s, _p_u_t_s, _f_p_u_t_s, _f_o_p_e_n, _f_d_o_p_e_n, _f_r_e_o_p_e_n, _f_t_e_l_l, _r_e_w_i_n_d, _f_e_o_f,
          _c_l_e_a_r_e_r_r, _f_e_r_r_o_r, _s_e_t_b_u_f, _s_e_t_l_i_n_e_b_u_f, _s_e_t_b_u_f_f_e_r, _s_e_t_v_b_u_f, _f_c_l_o_s_e,
          _f_f_l_u_s_h, _f_r_e_a_d, _f_w_r_i_t_e, _f_s_e_e_k, _f_g_e_t_p_o_s, _f_s_e_t_p_o_s, _f_l_o_c_k_f_i_l_e,
          _f_u_n_l_o_c_k_f_i_l_e, _t_e_m_p_n_a_m, _t_m_p_n_a_m, _t_m_p_f_i_l_e, _m_k_t_e_m_p, _m_k_s_t_e_m_p, _p_o_p_e_n,
          _p_c_l_o_s_e, _a_t_e_x_i_t, _p_r_i_n_t_f, _f_p_r_i_n_t_f, _v_p_r_i_n_t_f, _v_f_p_r_i_n_t_f, _s_c_a_n_f, _f_s_c_a_n_f,
          _o_p_e_n_d_i_r, _r_e_a_d_d_i_r, _s_c_a_n_d_i_r, _s_e_e_k_d_i_r, _c_l_o_s_e_d_i_r, _t_e_l_l_d_i_r, _d_u_p_2, _s_r_a_n_d,
          _r_a_n_d, _a_d_d_s_e_v, _a_d_d_s_e_v_e_r_i_t_y, _f_m_t_m_s_g, _s_e_t_c_a_t, _g_e_t_t_x_t, _l_f_m_t, _l_o_c_a_l_e_c_o_n_v,
          _n_l__l_a_n_g_i_n_f_o, _p_f_m_t, _s_e_t_l_a_b_e_l, _s_e_t_l_o_c_a_l_e, _s_t_r_f_t_i_m_e, _s_t_r_x_f_r_m, _s_t_r_c_o_l_l,
          _v_l_f_m_t, _v_p_f_m_t _m_a_l_l_o_c, _f_r_e_e, _c_a_l_l_o_c, _r_e_a_l_l_o_c, _m_a_l_l_o_p_t, _m_e_m_a_l_i_g_n
          _a_c_r_e_a_t_e, _a_m_a_l_l_o_c, _a_f_r_e_e, _a_c_a_l_l_o_c, _a_r_e_a_l_l_o_c, _a_m_a_l_l_o_p_t.

          ____SSSSGGGGIIII____RRRREEEEEEEENNNNTTTTRRRRAAAANNNNTTTT____FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS enables prototypes and definitions for
          reentrant versions of functions that are not thread safe by
          definition (usually due to returning pointers to static data).
          These alternatives are named _f_u_n_c_r and are described on the same
          manual page as the original, unsafe version.

          Functions that return pointers to static data are not reentrant.
          When there is no alternative interface threads must provide their
          own synchronization.  The following functions have non-obvious
          side-effects with respect to reentrancy.  _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee modifies many
          tables and static data.  In particular, any strings returned by
          _ssss_tttt_rrrr_eeee_rrrr_rrrr_oooo_rrrr and _gggg_eeee_tttt_tttt_xxxx_tttt will no longer be valid.  _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee also can
          affect other tables such as character class, collating sequence and
          numeric separator, which many routines access.  To be safe, no
          thread should be using any standard C library service when a change
          to the locale must be made.





                                                                        PPPPaaaaggggeeee 3333






iiiinnnnttttrrrroooo((((3333))))                                                              iiiinnnnttttrrrroooo((((3333))))



     (3T) These primitives implement a general terminal interface that
          provides control over asynchronous communications ports.  These are
          all in the standard C library.

     (3W) These functions constitute the wide-character library _llll_iiii_bbbb_wwww.  The
          functions are used to convert between multibyte and 32-bit wide
          characters, respectively.  This library is implemented as a shared
          object and an archive and is not automatically linked by the C
          compilation system.  Specify _----_llll_wwww on the _cccc_cccc command line to link with
          this library.  Declarations for these functions may be obtained from
          the include file <_w_i_d_e_c._h>.

     (3X) Various specialized libraries.  The files in which these libraries
          are found are given on the appropriate pages.
BBBBSSSSDDDD CCCCOOOOMMMMPPPPAAAATTTTIIIIBBBBIIIILLLLIIIITTTTYYYY
     As described in the discussion of Section 3B above,
          cc -D_BSD_COMPAT -o prog prog.c -lbsd

     selects maximum compatibility with BSD.  The ----llllbbbbssssdddd directive specifies
     that lllliiiibbbbbbbbssssdddd....aaaa be searched before lllliiiibbbbcccc....aaaa, which selects the BSD versions
     of functions that reside in both libraries (duplicated because of
     identical names yet differing semantics or arguments).  The routines that
     fall into this category are listed in the (3B) section above.  The BSD
     versions may also be selected on a case-by-case basis by prefixing the
     function name with BBBBSSSSDDDD when calling it in the program (e.g. _B_S_D_s_e_t_p_g_r_p).
     Specifying ----DDDD____BBBBSSSSDDDD____CCCCOOOOMMMMPPPPAAAATTTT or ----DDDD____BBBBSSSSDDDD____SSSSIIIIGGGGNNNNAAAALLLLSSSS on the compile line links with
     the BSD versions of the signal routines (_k_i_l_l, _k_i_l_l_p_g, _s_i_g_b_l_o_c_k, _s_i_g_n_a_l,
     _s_i_g_p_a_u_s_e, _s_i_g_s_e_t_m_a_s_k, and _s_i_g_v_e_c).  The program must include <_s_i_g_n_a_l._h>
     or <_s_y_s/_s_i_g_n_a_l._h>.  Note that a "#define _BSD_COMPAT" or "#define
     _BSD_SIGNALS" placed in the source program before the inclusion of the
     signal header file has the same effect as specifying the corresponding ----DDDD
     compile option.
     Specifying ----DDDD____BBBBSSSSDDDD____CCCCOOOOMMMMPPPPAAAATTTT or ----DDDD____BBBBSSSSDDDD____TTTTIIIIMMMMEEEE on the compile line links with
     the BSD versions of the _g_e_t_t_i_m_e_o_f_d_a_y and _g_e_t_t_i_m_e_o_f_d_a_y routines.  The
     program must include <_s_y_s/_t_i_m_e._h>. The "#define _BSD_COMPAT" or "#define
     _BSD_TIME" must be placed in the source program before the inclusion the
     time header file if the ----DDDD compile option is not specified.
     Defining ____BBBBSSSSDDDD____CCCCOOOOMMMMPPPPAAAATTTT gives the following additional BSD compatibility
     features over and above that given by ____BBBBSSSSDDDD____SSSSIIIIGGGGNNNNAAAALLLLSSSSand ____BBBBSSSSDDDD____TTTTIIIIMMMMEEEE:  you get
     the BSD version of _s_e_t_j_m_p(3) and including <_s_y_s/_t_y_p_e_s._h> will cause
     several additional macros and typedefs to be defined (e.g. _m_a_j_o_r, _m_i_n_o_r,
     _m_a_k_e_d_e_v for dealing with device numbers).  ____BBBBSSSSDDDD____CCCCOOOOMMMMPPPPAAAATTTT may affect more
     things in future releases.
     The System V and BSD versions of the directory routines (_o_p_e_n_d_i_r,
     _s_e_e_k_d_i_r, etc.)  differ greatly; inclusion of <_d_i_r_e_n_t._h> at the top of the
     your program selects the System V routines, <_s_y_s/_d_i_r._h> selects the BSD
     set.  See also _d_i_r_e_c_t_o_r_y(3C) and _d_i_r_e_c_t_o_r_y__b_s_d(3B).




                                                                        PPPPaaaaggggeeee 4444






iiiinnnnttttrrrroooo((((3333))))                                                              iiiinnnnttttrrrroooo((((3333))))



DDDDEEEEFFFFIIIINNNNIIIITTTTIIIIOOOONNNNSSSS
     A character [except a multibyte character; see _mmmm_bbbb_cccc_hhhh_aaaa_rrrr(3C)] is any bit
     pattern able to fit into a byte on the machine.  The null character is a
     character with value 0, conventionally represented in the C language as
     _\\\\_0000.  A character array is a sequence of characters.  A null-terminated
     character array (a _s_t_r_i_n_g) is a sequence of characters, the last of which
     is the _n_u_l_l _c_h_a_r_a_c_t_e_r.  A _s_t_r_i_n_g is a designation for a _n_u_l_l-_t_e_r_m_i_n_a_t_e_d
     _c_h_a_r_a_c_t_e_r _a_r_r_a_y.  The null string is a character array containing only
     the terminating null character.  A NULL pointer is the value that is
     obtained by casting _0000 into a pointer.  C guarantees that this value will
     not match that of any legitimate pointer, so many functions that return
     pointers return _NNNN_UUUU_LLLL_LLLL to indicate an error.  The macro _NNNN_UUUU_LLLL_LLLL is defined in
     _ssss_tttt_dddd_iiii_oooo_...._hhhh.  Types of the form _ssss_iiii_zzzz_eeee______tttt are defined in the appropriate header
     files.
FFFFIIIILLLLEEEESSSS
     _I_N_C_D_I_R                     usually _////_uuuu_ssss_rrrr_////_iiii_nnnn_cccc_llll_uuuu_dddd_eeee
     _L_I_B_D_I_R                     usually _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb
     _L_I_B_D_I_R_////_llll_iiii_bbbb_bbbb_ssss_dddd_...._aaaa            BSD Compatibility library
     _L_I_B_D_I_R_////_llll_iiii_bbbb_mmmm_...._aaaa              Math library
     _L_I_B_D_I_R_////_llll_iiii_bbbb_nnnn_ssss_llll_...._ssss_oooo           Network Services library
     _L_I_B_D_I_R_////_llll_iiii_bbbb_gggg_eeee_nnnn_...._{{{{_ssss_oooo_,,,,_aaaa_}}}}       Misc routines
     _L_I_B_D_I_R_////_llll_iiii_bbbb_gggg_llll_...._ssss_oooo            GL library
     _L_I_B_D_I_R_////_llll_iiii_bbbb_rrrr_pppp_cccc_ssss_vvvv_cccc_...._{{{{_ssss_oooo_,,,,_aaaa_}}}}    RPC services library
     _L_I_B_D_I_R_////_llll_iiii_bbbb_ssss_oooo_cccc_kkkk_eeee_tttt_...._ssss_oooo        Sockets Interface library
     _L_I_B_D_I_R_////_llll_iiii_bbbb_pppp_tttt_hhhh_rrrr_eeee_aaaa_dddd_...._ssss_oooo       POSIX thread library
     _L_I_B_D_I_R_////_llll_iiii_bbbb_wwww_...._{{{{_ssss_oooo_,,,,_aaaa_}}}}         Wide character library
     _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_iiii_bbbb_cccc_...._ssss_oooo_...._1111         Runtime Linker/Standard C library
SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _aaaa_rrrr_((((_1111_))))_,,,, _cccc_cccc_((((_1111_))))_,,,, _llll_dddd_((((_1111_))))_,,,, _nnnn_mmmm_((((_1111_))))_,,,, _iiii_nnnn_tttt_rrrr_oooo_((((_2222_))))_,,,, _uuuu_ssss_iiii_nnnn_iiii_tttt_((((_3333_PPPP_))))_,,,, _pppp_tttt_hhhh_rrrr_eeee_aaaa_dddd_((((_3333_PPPP_))))_,,,,
     _ffff_llll_oooo_cccc_kkkk_ffff_iiii_llll_eeee_((((_3333_SSSS_))))_,,,, _ssss_tttt_dddd_iiii_oooo_((((_3333_SSSS_))))
     _G_r_a_p_h_i_c_s _L_i_b_r_a_r_y _U_s_e_r'_s _G_u_i_d_e
NNNNOOOOTTTTEEEESSSS
     None of the functions, external variables, or macros should be redefined
     in the user's programs.  Any other name may be redefined without
     affecting the behavior of other library functions, but such redefinition
     may conflict with a declaration in an included header file.
     The header files in _I_N_C_D_I_R provide function prototypes (function
     declarations including the types of arguments) for most of the functions
     listed in this manual.  Function prototypes allow the compiler to check
     for correct usage of these functions in the user's program.  The _llll_iiii_nnnn_tttt
     program checker may also be used and will report discrepancies even if
     the header files are not included with _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee statements.  Definitions
     for Sections 2, 3C, and 3S are checked automatically.  Other definitions
     can be included by using the _----_llll option to _llll_iiii_nnnn_tttt.  (For example, _----_llll_mmmm
     includes definitions for _llll_iiii_bbbb_mmmm.)  Use of _llll_iiii_nnnn_tttt is highly recommended.
     Users should carefully note the difference between STREAMS and _s_t_r_e_a_m.
     STREAMS is a set of kernel mechanisms that support the development of
     network services and data communication drivers.  It is composed of
     utility routines, kernel facilities, and a set of data structures.  A
     _s_t_r_e_a_m is a file with its associated buffering.  It is declared to be a


                                                                        PPPPaaaaggggeeee 5555






iiiinnnnttttrrrroooo((((3333))))                                                              iiiinnnnttttrrrroooo((((3333))))



     pointer to a type _FFFF_IIII_LLLL_EEEE defined in _ssss_tttt_dddd_iiii_oooo_...._hhhh.
     In detailed definitions of components, it is sometimes necessary to refer
     to symbolic names that are implementation-specific, but which are not
     necessarily expected to be accessible to an application program.  Many of
     these symbolic names describe boundary conditions and system limits.
     In this section, for readability, these implementation-specific values
     are given symbolic names.  These names always appear enclosed in curly
     brackets to distinguish them from symbolic names of other
     implementation-specific constants that are accessible to application
     programs by header files.  These names are not necessarily accessible to
     an application program through a header file, although they may be
     defined in the documentation for a particular system.
     In general, a portable application program should not refer to these
     symbolic names in its code.  For example, an application program would
     not be expected to test the length of an argument list given to a routine
     to determine if it was greater than {ARG_MAX}.





































                                                                        PPPPaaaaggggeeee 6666